home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / nspr / prshm.h < prev    next >
C/C++ Source or Header  |  2006-04-20  |  10KB  |  290 lines
  1. /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is the Netscape Portable Runtime (NSPR).
  16.  *
  17.  * The Initial Developer of the Original Code is
  18.  * Netscape Communications Corporation.
  19.  * Portions created by the Initial Developer are Copyright (C) 1999-2000
  20.  * the Initial Developer. All Rights Reserved.
  21.  *
  22.  * Contributor(s):
  23.  *
  24.  * Alternatively, the contents of this file may be used under the terms of
  25.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27.  * in which case the provisions of the GPL or the LGPL are applicable instead
  28.  * of those above. If you wish to allow use of your version of this file only
  29.  * under the terms of either the GPL or the LGPL, and not to allow others to
  30.  * use your version of this file under the terms of the MPL, indicate your
  31.  * decision by deleting the provisions above and replace them with the notice
  32.  * and other provisions required by the GPL or the LGPL. If you do not delete
  33.  * the provisions above, a recipient may use your version of this file under
  34.  * the terms of any one of the MPL, the GPL or the LGPL.
  35.  *
  36.  * ***** END LICENSE BLOCK ***** */
  37.  
  38. /*
  39. ** prshm.h -- NSPR Shared Memory
  40. **
  41. ** NSPR Named Shared Memory API provides a cross-platform named
  42. ** shared-memory interface. NSPR Named Shared Memory is modeled on
  43. ** similar constructs in Unix and Windows operating systems. Shared
  44. ** memory allows multiple processes to access one or more common shared
  45. ** memory regions, using it as an inter-process communication channel.
  46. **
  47. ** Notes on Platform Independence:
  48. **   NSPR Named Shared Memory is built on the native services offered
  49. **   by most platforms. The NSPR Named Shared Memory API tries to
  50. **   provide a least common denominator interface so that it works
  51. **   across all supported platforms. To ensure that it works everywhere,
  52. **   some platform considerations must be accomodated and the protocol
  53. **   for using NSPR Shared Memory API must be observed.
  54. **
  55. ** Protocol:
  56. **   Multiple shared memories can be created using NSPR's Shared Memory
  57. **   feature. For each named shared memory, as defined by the name
  58. **   given in the PR_OpenSharedMemory() call, a protocol for using the
  59. **   shared memory API is required to ensure desired behavior. Failing
  60. **   to follow the protocol may yield unpredictable results.
  61. **   
  62. **   PR_OpenSharedMemory() will create the shared memory segment, if it
  63. **   does not already exist, or open a connection that the existing
  64. **   shared memory segment if it already exists.
  65. **   
  66. **   PR_AttachSharedMemory() should be called following
  67. **   PR_OpenSharedMemory() to map the memory segment to an address in
  68. **   the application's address space.
  69. **   
  70. **   PR_AttachSharedMemory() may be called to re-map a shared memory
  71. **   segment after detaching the same PRSharedMemory object. Be
  72. **   sure to detach it when done.
  73. **   
  74. **   PR_DetachSharedMemory() should be called to un-map the shared
  75. **   memory segment from the application's address space.
  76. **   
  77. **   PR_CloseSharedMemory() should be called when no further use of the
  78. **   PRSharedMemory object is required within a process. Following a
  79. **   call to  PR_CloseSharedMemory() the PRSharedMemory object is
  80. **   invalid and cannot be reused.
  81. **   
  82. **   PR_DeleteSharedMemory() should be called before process
  83. **   termination. After calling PR_DeleteSharedMemory() any further use
  84. **   of the shared memory associated with the name may cause
  85. **   unpredictable results.
  86. **   
  87. ** Files:
  88. **   The name passed to PR_OpenSharedMemory() should be a valid filename
  89. **   for a unix platform. PR_OpenSharedMemory() creates file using the
  90. **   name passed in. Some platforms may mangle the name before creating
  91. **   the file and the shared memory.
  92. **   
  93. **   The unix implementation may use SysV IPC shared memory, Posix
  94. **   shared memory, or memory mapped files; the filename may used to
  95. **   define the namespace. On Windows, the name is significant, but
  96. **   there is no file associated with name.
  97. **   
  98. **   No assumptions about the persistence of data in the named file
  99. **   should be made. Depending on platform, the shared memory may be
  100. **   mapped onto system paging space and be discarded at process
  101. **   termination.
  102. **   
  103. **   All names provided to PR_OpenSharedMemory() should be valid
  104. **   filename syntax or name syntax for shared memory for the target
  105. **   platform. Referenced directories should have permissions 
  106. **   appropriate for writing.
  107. **
  108. ** Limits:
  109. **   Different platforms have limits on both the number and size of
  110. **   shared memory resources. The default system limits on some
  111. **   platforms may be smaller than your requirements. These limits may
  112. **   be adjusted on some platforms either via boot-time options or by
  113. **   setting the size of the system paging space to accomodate more
  114. **   and/or larger shared memory segment(s).
  115. **
  116. ** Security:
  117. **   On unix platforms, depending on implementation, contents of the
  118. **   backing store for the shared memory can be exposed via the file
  119. **   system. Set permissions and or access controls at create and attach
  120. **   time to ensure you get the desired security.
  121. **
  122. **   On windows platforms, no special security measures are provided.
  123. **
  124. ** Example:
  125. **   The test case pr/tests/nameshm1.c provides an example of use as
  126. **   well as testing the operation of NSPR's Named Shared Memory.
  127. **
  128. ** lth. 18-Aug-1999.
  129. */
  130.  
  131. #ifndef prshm_h___
  132. #define prshm_h___
  133.  
  134. #include "prtypes.h"
  135. #include "prio.h"
  136.  
  137. PR_BEGIN_EXTERN_C
  138.  
  139. /*
  140. ** Declare opaque type PRSharedMemory.
  141. */
  142. typedef struct PRSharedMemory PRSharedMemory;
  143.  
  144. /*
  145. ** FUNCTION: PR_OpenSharedMemory()
  146. **
  147. ** DESCRIPTION:
  148. **   PR_OpenSharedMemory() creates a new shared-memory segment or
  149. **   associates a previously created memory segment with name.
  150. **
  151. **   When parameter create is (PR_SHM_EXCL | PR_SHM_CREATE) and the
  152. **   shared memory already exists, the function returns NULL with the
  153. **   error set to PR_FILE_EXISTS_ERROR.
  154. **
  155. **   When parameter create is PR_SHM_CREATE and the shared memory
  156. **   already exists, a handle to that memory segment is returned. If
  157. **   the segment does not exist, it is created and a pointer to the
  158. **   related PRSharedMemory structure is returned.
  159. **
  160. **   When parameter create is 0, and the shared memory exists, a
  161. **   pointer to a PRSharedMemory is returned. If the shared memory does
  162. **   not exist, NULL is returned with the error set to
  163. **   PR_FILE_NOT_FOUND_ERROR.
  164. **
  165. ** INPUTS:
  166. **   name -- the name the shared-memory segment is known as.
  167. **   size -- the size of the shared memory segment. 
  168. **   flags -- Options for creating the shared memory
  169. **   mode -- Same as is passed to PR_Open()
  170. **
  171. ** OUTPUTS: 
  172. **   The shared memory is allocated.
  173. **
  174. ** RETURNS: Pointer to opaque structure PRSharedMemory or NULL.
  175. **   NULL is returned on error. The reason for the error can be
  176. **   retrieved via PR_GetError() and PR_GetOSError();
  177. **
  178. */
  179. NSPR_API( PRSharedMemory * )
  180.     PR_OpenSharedMemory(
  181.         const char *name,
  182.         PRSize      size,
  183.         PRIntn      flags,
  184.         PRIntn      mode
  185. );
  186. /* Define values for PR_OpenShareMemory(...,create) */
  187. #define PR_SHM_CREATE 0x1  /* create if not exist */
  188. #define PR_SHM_EXCL   0x2  /* fail if already exists */
  189.  
  190. /*
  191. ** FUNCTION: PR_AttachSharedMemory()
  192. **
  193. ** DESCRIPTION:
  194. ** PR_AttachSharedMemory() maps the shared-memory described by
  195. ** shm to the current process. 
  196. **
  197. ** INPUTS: 
  198. **   shm -- The handle returned from PR_OpenSharedMemory().
  199. **   flags -- options for mapping the shared memory.
  200. **   PR_SHM_READONLY causes the memory to be attached 
  201. **   read-only.
  202. **
  203. ** OUTPUTS:
  204. **   On success, the shared memory segment represented by shm is mapped
  205. **   into the process' address space.
  206. **
  207. ** RETURNS: Address where shared memory is mapped, or NULL.
  208. **   NULL is returned on error. The reason for the error can be
  209. **   retrieved via PR_GetError() and PR_GetOSError();
  210. **
  211. **
  212. */
  213. NSPR_API( void * )
  214.     PR_AttachSharedMemory(
  215.         PRSharedMemory *shm,
  216.         PRIntn  flags
  217. );
  218. /* Define values for PR_AttachSharedMemory(...,flags) */ 
  219. #define PR_SHM_READONLY 0x01
  220.  
  221. /*
  222. ** FUNCTION: PR_DetachSharedMemory()
  223. **
  224. ** DESCRIPTION:
  225. **   PR_DetachSharedMemory() detaches the shared-memory described
  226. **   by shm. 
  227. **
  228. ** INPUTS: 
  229. **   shm -- The handle returned from PR_OpenSharedMemory().
  230. **   addr -- The address at which the memory was attached.
  231. **
  232. ** OUTPUTS:
  233. **   The shared memory mapped to an address via a previous call to
  234. **   PR_AttachSharedMemory() is unmapped.
  235. **
  236. ** RETURNS: PRStatus
  237. **
  238. */
  239. NSPR_API( PRStatus )
  240.     PR_DetachSharedMemory(
  241.         PRSharedMemory *shm,
  242.         void  *addr
  243. );
  244.  
  245. /*
  246. ** FUNCTION: PR_CloseSharedMemory()
  247. **
  248. ** DESCRIPTION:
  249. **   PR_CloseSharedMemory() closes the shared-memory described by
  250. **   shm.
  251. ** 
  252. ** INPUTS:
  253. **   shm -- The handle returned from PR_OpenSharedMemory().
  254. **
  255. ** OUTPUTS:
  256. **   the shared memory represented by shm is closed
  257. **
  258. ** RETURNS: PRStatus
  259. **
  260. */
  261. NSPR_API( PRStatus )
  262.     PR_CloseSharedMemory(
  263.         PRSharedMemory *shm
  264. );
  265.  
  266. /*
  267. ** FUNCTION: PR_DeleteSharedMemory()
  268. **
  269. ** DESCRIPTION:
  270. **   The shared memory resource represented by name is released.
  271. **
  272. ** INPUTS:
  273. **   name -- the name the shared-memory segment
  274. **
  275. ** OUTPUTS:
  276. **   depending on platform, resources may be returned to the underlying
  277. **   operating system.
  278. **
  279. ** RETURNS: PRStatus
  280. **
  281. */
  282. NSPR_API( PRStatus )
  283.     PR_DeleteSharedMemory( 
  284.         const char *name
  285. );
  286.  
  287. PR_END_EXTERN_C
  288.  
  289. #endif /* prshm_h___ */
  290.